/*
 * Copyright 2008 Max Kugland
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.splink.library.logging {
	import org.splink.library.IFinalizable;
	import org.splink.library.logging.logoutput.ILogOutput;

	/**
	 * The basic interface for <code>ILogger</code> implementations. A default implementation
	 * is the <code>Logger</code>.
	 * 
	 * @see Logger
	 * @author Max Kugland
	 */
	public interface ILogger extends IFinalizable {
		/**
		 * You can specify via <code>setRange</code> which LogLevels will be logged. If you change 
		 * the <code>LogRange</code> during runtime, the <code>ILogger</code> implementation then will 
		 * start to only log messages with an <code>LogLevel</code> within the new <code>LogRange</code>
		 * 
		 * @param range the <code>LogRange</code> which will be logged.
		 * @see Range
		 * @see LogLevel
		 */
		function set range(range : LogRange) : void;

		/**
		 * You can specify a base package as an additional filter, to restrict what is logged. All 
		 * logs which occur within the specified package or below are logged, all other logs are
		 * ignored. Usually the basePackage is defined with the <code>ILoggerFactory</code>.
		 * 
		 * @param pack the package path, should look alike "org.splink.library.logging"
		 */
		function set basePackage(pack : String) : void;

		/**
		 * Retrieves the <code>ILogOutput</code> implementing instance for the given class.
		 * 
		 * @param clazz the class for which to return the corresponding <code>ILogOutput</code>
		 * implementation instance
		 * @return an <code>ILogOutput</code> implementation instance
		 */
		function getLogOutput(clazz : Class) : ILogOutput;

		/**
		 * Logs a message for the given <code>LogLevel</code>. Logs the log level, the message and 
		 * if the flash movie is played by the flash debug player also logs the class, function and
		 * line number in which the log statement occurred.
		 * debug player.
		 * 
		 * @param level LogLevel for the message
		 * @param message custom message to be logged
		 * @param ignoreRange by default set to false. If set to true the message will be logged 
		 * whatever <code>LogRange</code> is set
		 * @see LogLevel
		 */
		function log(level : uint, message : *, ignoreRange : Boolean = false) : void;

		/**
		 * Watches a given object and logs a message when its collected by the garbage collector.
		 * 
		 * @param obj the object to watch
		 * @param id an id for the object. if no id is defined the objects qualified class name will
		 * be used as id
		 */
		function logGarbageCollection(obj : *, id : String = null) : void;
		
		/**
		 * Shortcut to fire a trace log message
		 */
		function trace(...args) : void;
		
		/**
		 * Shortcut to fire an info log message
		 */
		function info(...args) : void;
		
		/**
		 * Shortcut to fire a debug log message
		 */
		function debug(...args) : void;
		
		/**
		 * Shortcut to fire a warn log message
		 */
		function warn(...args) : void;
		
		/**
		 * Shortcut to fire an error log message
		 */
		function error(...args) : void;
		
		/**
		 * Shortcut to fire a fatal log message
		 */
		function fatal(...args) : void;
	}
}
